home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / comm / amipop17.zip / AMIPOP.DOC < prev    next >
Text File  |  1993-11-15  |  13KB  |  398 lines
  1.  
  2.  
  3.                 AmiPOP - A POP3 Client
  4.  
  5.                   ⌐ 1993 Scott Ellis
  6.  
  7.  
  8.  
  9. Introduction-
  10.  
  11.     What it is -
  12.  
  13.         AmiPOP is a POP3 Client for AmigaDOS.  It was written directly from
  14.         the POP3 RFC (RFC #1225). AmiPOP is only a simple transport mechanism
  15.         for moving electronic mail messages between a POP-Host, typically
  16.         a mainframe, and your local AmigaDOS system.  The advantage of POP
  17.         over other transports such as SMTP is that all E-mail can still be
  18.         directed to the mainframe system.  This is of primary importance when
  19.         either a dialup line is used, which has a new IP address for each
  20.         connection, or when a user uses many machines, and wishes to be able
  21.         to transparently read mail on all of them.
  22.  
  23.     What it's not -
  24.  
  25.         AmiPOP is not intended to be a do-everything-mail-reader-reminder-slicer-dicer
  26.         program.  AmiPOP is meant to simply transport mail from a host to your Amiga.
  27.         That's it.  Nothing else.  The "Notify" function inlcuded in AmiPOP is intended
  28.         to be a stopgap measure only, and was included as a request of an especially helpful
  29.         beta-tester.  The "Notify" function will never grow.  If you want to do exotic things
  30.         when you get new mail, use another utility, like Mike Schwarz's 'Mail-Minder', or
  31.         Scott Ellis' (me) program 'Sabot'.
  32.  
  33.     What you need -
  34.  
  35.         AmiPOP requires Commodore's (as yet unreleased) AS225r2 package, and a
  36.         machine running a POP3 daemon. (More on this later)
  37.         AS225r2 requires AmigaDOS 2.0 or higher, and this is therefore required
  38.         by AmiPOP as well.
  39.  
  40.     AmiPOP features -
  41.  
  42.         ╖ AUISG compliant (or at least it tries to be!)
  43.         ╖ Makes heavy use of 2.0 (and higher) functions such as ReadArgs,
  44.           utility.library, GadTools, and 2.0 functions in Amiga.lib.
  45.         ╖ Written from RFC 1225, not a port of a Unix or a PC application.
  46.         ╖ Small code size, and low system resource usage.
  47.         ╖ Commodities interface
  48.  
  49.  
  50. Options -
  51.  
  52.     Window -
  53.  
  54.         Each gadget in the window may be activated from the keyboard by using
  55.         the underlined character in the gadget label (case insensitive). Menu
  56.         options can also be accessed via their key combination (Right Amiga key)
  57.  
  58.         Activating a string or integer gadget enables the information to be
  59.         immediately typed in, and the gadget can be de-activated either by
  60.         the RETURN key, or by cycling to the next gadget with the TAB key.
  61.  
  62.         After activating one of the string or integer gadgets, the TAB key
  63.         allows cycling through each of the gadgets.  The order is:
  64.  
  65.             ╖ POP Host
  66.             ╖ How Often
  67.             ╖ Username
  68.             ╖ Password
  69.             ╖ Mail Box
  70.  
  71.         If "How Often" is disabled, then it is ignored, and the gadget is skipped
  72.         during the TAB-Cycle.
  73.  
  74.         Gadgets -
  75.  
  76.             POP Host -
  77.  
  78.                 This is the address of the machine which is running the
  79.                 POP3 daemon.  It can either be an IP address, a full
  80.                 name and domain, or just the name (if the site is in
  81.                 your inet:DB/Hosts file, or in your local domain).
  82.  
  83.             Username -
  84.  
  85.                 Username is your login name on the POP Host machine.
  86.                 It is used in determining which mailbox to look at,
  87.                 and which password to accept.
  88.  
  89.             Password -
  90.  
  91.                 This is the password for Username on machine POP Host.
  92.                 The Password gadget is a special string gadget which
  93.                 will NOT echo what you type.  Instead, you will see
  94.                 a bullet ( "╖" ) for each character you type.  The
  95.                 Password gadget is more limited in it's editing abilities
  96.                 then the other gadget, and will only allow you to delete
  97.                 characters from the end of the password, or clear the
  98.                 entire gadget.
  99.  
  100.             Mail Box -
  101.  
  102.                 Mail Box is the FULL AmigaDOS path and filename that
  103.                 you would like the mail stored in on your Amiga.
  104.                 Most UUCP mail-readers require this be "UUMAIL:Username",
  105.                 but you are free to choose whatever you like.
  106.  
  107.             Append to MailBox -
  108.  
  109.                 When checked, this gadget will append all incoming mail
  110.                 to the file listed in the MailBox gadget.  If it is
  111.                 unchecked, new mail will overwrite the mailbox.  This
  112.                 gadget is most useful in conjuction with the "Delete
  113.                 Messages" gadget.
  114.  
  115.             Delete Messages -
  116.  
  117.                 If Delete Messages is checked, it will delete the mail
  118.                 message on POP Host after it is downloaded.  Caution
  119.                 is advised with this gadget, since once mail is deleted
  120.                 on the POP Host, there is no way to retrieve it.
  121.                 This gadget is best used with "Append to MailBox".
  122.  
  123.             Check Periodically -
  124.  
  125.                 When this gadget is marked, mail will be transfered
  126.                 from the POP Host on a time schedule.  This schedule
  127.                 is defined in "How Often".
  128.  
  129.             How Often -
  130.  
  131.                 This gadget defines the number of minutes that should
  132.                 elapse between queries for mail to POP Host.  If
  133.                 Check Periodically is not checked, this gadget will
  134.                 be disabled, and have no effect.
  135.  
  136.             Check Now -
  137.  
  138.                 Check Now will immediately query POP Host for mail.
  139.                 It is primarily used for impatient people who cannot
  140.                 wait for the Check Periodically time to elapse, or
  141.                 who would like the mail checked manually, instead
  142.                 of periodically.
  143.  
  144.         Menus -
  145.  
  146.             Hide -
  147.  
  148.                 This option will close the AmiPOP window, but not quit
  149.                 AmiPOP.  The window may be reopened either via the
  150.                 hotkey (If specified) or with Commodities Exchange.
  151.  
  152.             About... -
  153.  
  154.                 Opens a requester with the AmiPOP authors name.
  155.  
  156.             Quit -
  157.  
  158.                 Quits the AmiPOP program.  This is identical to
  159.                 sending AmiPOP a Control-C character, or clicking
  160.                 on the close box in the AmiPOP window.
  161.  
  162.     Command Line -
  163.  
  164.             Command line options maybe be given either on the command line
  165.             when starting AmiPOP from a shell, or as ToolTypes when
  166.             using AmiPOP from an icon.
  167.  
  168.             AmiPOP uses ReadArgs to process command line and tooltype
  169.             arguments passed to it.
  170.  
  171.             Username -
  172.  
  173.                 This is identical to the Username gadget in the
  174.                 AmiPOP window.  Specifying a username on the
  175.                 command line avoids having to enter it into the
  176.                 AmiPOP window.
  177.  
  178.             Password -
  179.  
  180.                 This is identical to the Password gadget in the
  181.                 AmiPOP window.  Specifying a password on the
  182.                 command line avoids having to enter it into the
  183.                 AmiPOP window.
  184.  
  185.             POPHost -
  186.  
  187.                 This is identical to the POP Host gadget in the
  188.                 AmiPOP window.  Specifying a POP Host on the
  189.                 command line avoids having to enter it into the
  190.                 AmiPOP window.
  191.  
  192.             MailDir -
  193.  
  194.                 This is identical to the MailBox gadget in the
  195.                 AmiPOP window.  Specifying a MailBox on the
  196.                 command line avoids having to enter it into the
  197.                 AmiPOP window.
  198.  
  199.             CheckPer -
  200.  
  201.                 When given, this switch specifies that the
  202.                 Check Periodically function should be enabled.  It
  203.                 is identical to making Check Periodically enabled
  204.                 in the AmiPOP window.
  205.  
  206.             Time -
  207.  
  208.                 Time, followed by an integer will place a default
  209.                 value into the How Often gadget in the AmiPOP
  210.                 window.  If CheckPer is not also given, or if the
  211.                 Check periodically gadget in the AmiPOP window is
  212.                 not active, this setting has no effect.
  213.  
  214.             Delete -
  215.  
  216.                 When present, this switch enables the Delete Messages
  217.                 function of AmiPOP.  It is identical to the Delete
  218.                 Messages gadget in the AmiPOP window.
  219.  
  220.             Append -
  221.  
  222.                 When present, Append activates the Append to MailBox
  223.                 feature of AmiPOP.  It is identical to activating the
  224.                 Append to MailBox gadget in the AmiPOP window.
  225.  
  226.             NoWindow -
  227.  
  228.                 When the NoWindow flag is given, it instructs AmiPOP not
  229.                 to open it's window my default.  This is useful when
  230.                 running AmiPOP from WBStartup, or from a script.
  231.                 The AmiPOP window may later be opened by the hotkey, or
  232.                 via Commodities Exchange.
  233.  
  234.             Port -
  235.  
  236.                 Normally, POP3 uses port 110 on the POP Host machine.
  237.                 When the Port switch is given, followed by an integer,
  238.                 that will be used in attempts to connect to the POP3
  239.                 daemon on the POP Host, instead of port 110.
  240.  
  241.             Notify -
  242.  
  243.                 The Notify switch will force AmiPOP to open a requester
  244.                 when it detects that you have new mail.  By default,
  245.                 AmiPOP does not notify the user of new mail.
  246.  
  247.             Cx_Popkey -
  248.  
  249.                 This is the hotkey that AmiPOP will use.  When pressed,
  250.                 AmiPOP will open it's window, if it is not already open.
  251.                 Any valid hotkey combination may be given.  If Cx_Popkey
  252.                 is not specified, AmiPOP will not add itself to the
  253.                 input chain, and will not cause any system performance
  254.                 decrease.
  255.  
  256.             PubScreen -
  257.  
  258.                 Giving AmiPOP the name of a public screen will cause the AmiPOP
  259.                 window to open on that public screen.  If AmiPOP cannot open on the
  260.                 specified screen, or if no screen is specified, AmiPOP will open on
  261.                 the default public screen (normally WorkBench).
  262.  
  263. Misc Notes -
  264.  
  265.     POP3 Daemon -
  266.  
  267.             A POP3 Daemon does not need root privledges to install and operate.
  268.             Any user may run a POP3 Daemon, so long as it is configured to
  269.             use a non-blocked port (typically those above 1024).
  270.  
  271.     Cautions -
  272.  
  273.             It is possible that not all of the bugs have been worked out of
  274.             AmiPOP yet, and there are therefore some pitfalls which the user
  275.             should keep in mind.
  276.  
  277.             Foremost, Delete Messages WILL delete E-mail messages on POP Host,
  278.             so be cautious.  If AmiPOP encounters a problem during the
  279.             transmission of a message, it will usually abort, and keep all
  280.             the messages after and including the one with which it had
  281.             problems with, on the POP Host, but there is always the
  282.             possibility that the mailbox could be corrupted by a semi-functional
  283.             POP3 Daemon on the POP Host, so be aware that your mailbox COULD
  284.             get mangled.
  285.  
  286.             If for any reason, AmiPOP must abort abruptly, it attempts to
  287.             send the QUIT signal to the POP3 Daemon, but depending on the
  288.             circumstances of the AmiPOP failure (i.e., power failure or
  289.             general system crash), this may not be possible, and a
  290.             brain-dead POP3 Daemon could be left running on the POP Host,
  291.             preventing any further POP3 connections until that process
  292.             is killed.  Please review the CPU and Time limits for processes
  293.             under Unix, as well as POP3 Daemon return codes.
  294.  
  295.     Thanks -
  296.  
  297.             Thanks for help in creating AmiPOP are far and wide, and generally
  298.             encompass the #amiga and #amigatech group on IRC.  Specifically,
  299.             the author would like to express his deepest gratitude to
  300.             the following people:
  301.  
  302.             Michael B. Smith -    LOTS and LOTS of help with sockets, SMTP,
  303.                         NNTP, the OS, and just about everything.
  304.  
  305.             Christopher A. Wolf -    Chris provided invaluable help regarding
  306.                         the commodities and ReadArgs portion
  307.                         of this code, as well as general
  308.                         help on how in the heck to get this
  309.                         POP program working.
  310.  
  311.             Ken C. Dyke -        The very cool Password gadget edithook
  312.                         would have had me stumped forever, had
  313.                         it not been for a nice bit of code that
  314.                         Ken just happened to have laying around. :-)
  315.  
  316.             Michelle R. Ketcham -    She found my stupid mistakes, and also
  317.                         forced me to write AmiPOP in the first
  318.                         place.
  319.  
  320.             I'm sure I'm forgetting lots and lots of people, and I hate that.
  321.  
  322.        Bugs -
  323.  
  324.             None left that I know of.
  325.  
  326.     To Do -
  327.  
  328.         ╖ Allow AmiPOP to get signals while it's transfering.  Currently it can't
  329.           be hidden/quit while a transfer is in progress.  This is lame.
  330.  
  331.     Author Info -
  332.  
  333.         The author of AmiPOP may be contacted at:
  334.  
  335.         Scott Ellis :    sellis@ucssun1.sdsu.edu
  336.                         ScottE on IRC
  337.                         3640 Mt Everest Blvd, San Diego, CA, 92111 (USA)
  338.  
  339.         Please feel free to contact me, and let me know if you find any bugs
  340.         in AmiPOP, or if you find any more efficient ways of doing things.
  341.         I'm interested in hearing if anyone actually USES this program, or if it's
  342.         just me. ;-)
  343.  
  344.         The source and binary to this program are freeware.  Do with it whatever
  345.         you like, just remember to give me some credit if you get rich and
  346.         famous.
  347.  
  348. History -
  349.  
  350.     1.0    -    Initial release
  351.  
  352.     1.1    -    Fixed a few parts of the code where it was possible that we could
  353.             do something with a window that wasn't opened yet.
  354.  
  355.             Attempted to fix End Of Message problems.
  356.  
  357.     1.2    -    End of Message problem fixed some more. ;-) Still a big kludge.
  358.  
  359.             Added busy pointer during dopop() routine.
  360.  
  361.             Changed "Bummer" to "Ok" in most requesters.
  362.  
  363.             Minor reorganization.
  364.  
  365.     1.3    -    Bug Fix.
  366.  
  367.     1.4    -    Released with INetUtils via Michael B. Smith.  Thanks Michael!
  368.  
  369.     1.5 -    Major Code changes.
  370.  
  371.             Variables now dynamically allocated to reduce executable size.
  372.  
  373.             Adding of "From" header revamped.
  374.  
  375.             Added forgotten PrintError() in ReadArgs() section!  Oops!
  376.  
  377.             Fixed longstanding bug of missing the first bit of a message when it was sent
  378.             in the same packet as the +OK string.  Fixed now.
  379.  
  380.             INetUtils release delayed due to circumstances beyind my control.  V1.5
  381.             released with INetUtils-1.0.
  382.  
  383.     1.6 -    Moved 2 checkboxes over a tad, in hopes of avoiding conflics with window border
  384.             when using certain fonts.
  385.  
  386.             Changed location of "Notify" window in code, and also make AmiPOP sendstat()
  387.             after the "Notify" window is satisfied, in case new messages arrive.
  388.             Thanks to Stan Burton for that suggestion.
  389.  
  390.     1.7    -    Finally fixed the checkbox font rendering...really, honest, I did this time.
  391.  
  392.             Reduced code size by performing some magic. (hehehe)
  393.  
  394.             Added PubScreen keyword, which should have been in there from the beginning.
  395.  
  396.  
  397.  
  398.